✨ feat(fmt): a string-formatting engine unifying repr, str, format, and the IPython reprs - #855

Every product-style combination needed its own FORMAT_PRESETS entry, so
html/latex only ever existed with the multiplication separator baked in --
there was no way to ask for html-bare or latex-short without adding a new
dict row per combination, and three independent axes (markup, array
verbosity, separator) would need one entry each for every combination.

Parse a spec as a set of up to three optional tokens instead: markup (html,
latex; default text), array (short; default the compact form), separator
(mul, bare; default mul). Order doesn't matter -- "html-bare" and "bare-html"
are the same request -- but "<markup>-<array>-<separator>" is the canonical
spelling used in docs and error messages. The existing single-word presets
(mul, bare, short, html, latex) are now the case where every component but
one is omitted, not a separate alias table, which is what makes "html" mean
"html-mul" for free rather than needing its own entry.

FORMAT_PRESETS keeps only the call-style entries (full, compact, dims) that
don't fit this grammar. bad_spec's error message and the pspec/pspec_fallback
docstrings describe both.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

…e into the DSL

The array component was share/compact only, and the unit always rendered its
short/symbol name -- a spec like ".3g" only ever worked scalar-only, through
the unrelated pspec_fallback path, with no way to combine it with markup, a
separator, or a summary array. Extend both axes so they compose with the rest
of the grammar:

- The array component may carry a trailing Python format spec, applied per
  element via numpy.array2string's formatter (e.g. "mul-.3g", "compact-.3g",
  or bare ".3g" combined with any other token). "compact" is now a nameable
  array token (previously implicit-only) so it has something to attach a
  value spec to on its own. "short" (a shape/dtype summary) has no per-element
  values to format, so combining it with a value spec is rejected.
- A new unit component, "long", renders astropy's long_names in place of the
  short/symbol form, falling back to the short form (not raising) for a
  composite or dimensionless unit with no long name.

A value spec still needs a real DSL token to activate this path -- a bare
".3g" or ":>10" (":" as a fill character) has no keyword in it at all, so it
is untouched and keeps going through the unchanged, scalar-only
pspec_fallback, exactly as before.

Fixes a collision this surfaced: "compact" is both a pre-existing call-style
FORMAT_PRESETS key and now a valid array-component token. pspec checks
FORMAT_PRESETS before parsing the DSL so a bare f"{q:compact}" keeps its
original meaning; only "compact" combined with something else (e.g.
"compact-.3g") reaches the DSL.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

…"values"

"compact" was both a pre-existing call-style FORMAT_PRESETS key and the array
component's nameable default-form token -- and never actually load-bearing as
the latter: a bare "compact" is always intercepted by FORMAT_PRESETS (checked
first), and "compact" combined with anything else is indistinguishable from
using any other real token (e.g. "mul", already a pure no-op default itself)
as the anchor. So "compact-.3g" and "mul-.3g" always produced the identical
parsed spec -- the word bought no expressiveness, only a naming collision.

Rename it to "values", which cannot collide with any FORMAT_PRESETS entry and
still reads clearly ("show the values, at this precision"). The ordering fix
(FORMAT_PRESETS checked before the DSL parse) stays regardless, as general
defensive design for the next token that gets added.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

The format DSL had two disjoint systems -- a FORMAT_PRESETS table for
call-style renderings and a keyword DSL for product-style ones -- and three
root causes between them:

- Two systems that could not compose. `html-compact` leaked past the DSL into
  float.__format__ and raised "Invalid format specifier 'compact' for object
  of type 'float'".
- The value spec was parsed *by elimination* ("whatever is left after the
  keywords"), so `mul-.2f-.3g` silently rejoined into one garbage spec.
- The value spec had two implementations. `.2f` went through pspec_fallback
  (scalar-only, space-joined); `mul-.2f` went through the engine (array-
  capable, '*'-joined) -- so the same spec meant different things depending on
  whether an unrelated keyword happened to be present.

Replace all of it with one grammar. A spec is a '-'-joined run of keywords,
then an optional Python format spec applied per element. The parse is total
and left-to-right: consume keywords, and the first non-keyword token ends
keyword parsing -- everything from there, including any further '-', is the
value spec. That single rule removes the elimination pass and makes a format
spec's own '-' (sign flag "-.2f", fill char "->10.2f") unambiguous.

Six axes, one flat pairwise-disjoint keyword namespace (enforced by a test,
which is what makes order-independence sound rather than hopeful): layout
(call|product), value (array|values|type), markup (text|html|latex), unit
(symbol|name|dim), separator (mul|bare), abbreviation (abbrev). Naming an axis
the chosen layout lacks is a typed error, never a silent no-op. Aliases
(compact, full, dims) expand textually into core keywords, so they can never
mean anything the grammar cannot say.

repr and str are now the same renderer reached with a different Spec, with
unxt.config supplying the components -- the empty spec stops being a special
case. The public config traits keep their spelling; VALUE_FROM_SHORT_ARRAYS is
the one place the two vocabularies meet. call layout still routes through
__pdoc__, which is load-bearing: that is where reconstruction lives, so
eval(repr(usys)) == usys still holds.

BREAKING CHANGE: the product-style default separator is now `bare`, so
`f"{q:.2f}"` is '3.14 m' (astropy-shaped) and `f"{q:html}"` no longer shows a
'*'. `short` is renamed `type` and `long` is renamed `name`. FORMAT_PRESETS
and pspec_fallback are gone. A value spec now formats each element of an
array instead of raising TypeError.

Also fixes value_str collapsing the full-array form onto the type summary:
it pinned short_arrays=True and always passed the summary-building custom
hook, so `array` and `type` rendered identically.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Ponytail-review pass on the new grammar. Three duplications, all of them free
to drift out of sync:

- `parse_spec` spelled out every axis default a second time as
  `seen.get(axis, default)`, alongside the `Spec` field defaults. Axis names
  are exactly `Spec._fields`, so the scanned axes go straight in as
  `Spec(**seen, value_spec=...)` and unset ones fall to the field default.
  Validation moves after construction and reads the built spec. A test pins
  the axis-name/field-name correspondence the call now relies on.
- `VALUE_FROM_SHORT_ARRAYS` was hand-written as the exact inverse of
  `_SHORT_ARRAYS`; derive it by inversion instead.
- `_SEPARATORS` was a two-entry table read at exactly one call site; inline
  it there.

No behaviour change.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

…registrable

The engine's docstring claimed it "knows nothing about quantities, units, or
unit systems". That was false, and a downstream package could not in fact
extend it -- registering an axis died with `TypeError: Spec.__new__() got an
unexpected keyword argument`, because `Spec` was a closed NamedTuple. Five
couplings, now cut:

- `Spec` is a frozen Mapping, so a downstream axis is read exactly like a
  built-in one. Build with `Spec.of(**overrides)`, which fills defaults from
  the registry -- writing the mapping out by hand leaves a hole that surfaces
  as a KeyError once a later axis is registered.
- The vocabulary is a registry. `register_axis` / `register_alias` replace the
  hardcoded `_KEYWORDS` / `_LAYOUT_AXES` / `ALIASES` tables. An `Axis` carries
  its keywords, default, and a per-layout translation to renderer kwargs --
  where membership *is* applicability, so the layout-scope check falls out of
  the same table.
- `render` no longer hardcodes unxt's `__pdoc__` kwargs. `quote_units` and
  `show_units` are what the `abbrev` and `unit` axes translate to, declared in
  unxt's layer, and the product renderer forwards every axis it does not own
  to `pparts` -- which is what lets a type act on an axis the engine has never
  heard of.
- jax/numpy leave the engine. `value_str` and the `custom_pdoc_*` hooks were
  only ever called by consumers.
- `unxt._src.fmt` becomes a package: `engine` (domain-agnostic, imports
  nothing from unxt/jax/numpy/astropy) and `axes` (unxt's axes, aliases and
  array helpers). coordinax and galax add theirs as peers of `axes`.

Three tests hold the seam: one asserts the engine's import list stays clean,
one registers a fake downstream axis and checks it is indistinguishable from a
built-in (order-independence, defaults, aliasing, layout scoping), and one
checks registration rejects a name collision in both directions.

That last one caught a real gap while being written: `register_alias` guarded
against keyword collisions but silently overwrote an existing alias -- the
exact failure this registry exists to prevent.

BREAKING CHANGE: `Spec` is a Mapping, not a NamedTuple -- `spec.markup`
becomes `spec["markup"]`, and construction goes through `Spec.of`.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

…ract

`unxt._fmt` re-exported 23 names, most of them engine internals that nothing
outside the engine calls. Widening a surface later is easy and narrowing it is
not, so export only what a downstream package provably needs and let the rest
be reached at `unxt._src.fmt` until something outside this repo asks:

- join in:            pparts, PPart, PGroup
- extend the grammar: Axis, register_axis, register_alias
- render:             pspec, render, Spec

That is 9. Dropped: ALIASES, AXES, MARKUPS, REQUIRED_MARKUP_KEYS,
VALUE_FROM_SHORT_ARRAYS, bad_spec, custom_pdoc_no_kind, custom_pdoc_noarray,
doc_to_str, parse_spec, parts_to_doc, parts_to_markup, unwrap_math, value_str.
None had a caller outside `unxt._src`; unxt's own modules already reach the
engine by the internal path, so nothing moved but the doctest imports.

The shim's `pparts` example now renders through `pspec` rather than
`parts_to_markup`, which is both the public path and the one a downstream type
would actually take -- and it gained a case showing the unit axis reaching
nested quantities through a type that has never heard of it. The docs' axis
example is likewise executable now, so "a downstream axis is first-class" is
checked rather than asserted.

Also drops a stale `FORMAT_PRESETS` reference left in a docstring by the
grammar rewrite.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

The trailing Python format spec was a reserved `Spec` key beside the axes,
not a value of one. Two problems came with that:

- It made an invalid state representable. `value` and `value_spec` described
  one thing -- how the payload renders -- so `Spec(value="type",
  value_spec=".2f")` was constructible and meaningless, and needed a
  hand-written consistency check to reject it.
- It leaked unxt's vocabulary into the domain-agnostic engine. That check read
  `resolved.get("value") != "values"` and `layout != "product"`: the axis
  name, the keyword and the layout name are all defined in `axes.py`, unxt's
  layer. The engine/axes seam test could not catch it, because those are
  string literals rather than imports.

An axis may now declare `free_text=(<layouts>)`, saying its value may be
arbitrary text instead of a keyword in those layouts. unxt's `value` axis
claims it for `product`. The engine's job becomes generic: append the trailing
run to whichever axis claims free text, and error if that axis is already set
or the layout does not accept text. At most one axis may claim it, enforced at
registration -- the scan rule makes the trailing run terminal, so there is only
one to give.

`type-.2f` is now caught by the ordinary "value is set twice" rule, and no
axis name, keyword or layout name is hardcoded in the engine any more.

BREAKING CHANGE: `Spec` no longer has a `value_spec` key. `spec["value"]` is
either a keyword value or the format spec; ask `free_text_of(spec)` which.

Docs restructured to match: `conventions.md` keeps a short statement of the
conventions plus an example, and the full grammar, axis table, extension and
layering docs move to a new `guides/formatting.md`. A reference manual had no
business in a conventions page.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

…lper

Ponytail-review pass on the free-text machinery:

- `_FREE_TEXT_AXIS` was a module-level list standing in for a nullable
  singleton, hand-maintained by `register_axis` and read via `[0]` in four
  places. Derive it from `AXES` instead, so it cannot fall out of step with
  the registry -- the same fix as `VALUE_FROM_SHORT_ARRAYS`.
- `free_text_of` was a public-shaped helper with one caller and no export.
  Inline it into `pspec` until a second caller exists.
- Dropped the "no axis accepts free text" guard: unreachable here, since
  unxt's layer always registers one, and untested. Speculative cover for a
  state the standalone package does not have yet either.

Also corrects the previous commit message, which told downstream to ask
`free_text_of(spec)`. That name was never exported, so the instruction did
not work as written; it is now gone rather than half-available.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

…olds

A verbosity pass over the engine's comments and docstrings, keeping rationale
a current reader needs and dropping post-mortems of superseded revisions:

- `parse_spec`'s inline comment argued its design against the old `value_spec`
  key -- a comparison no reader of this code can see.
- `value_str` carried eleven lines of comment over two lines of code, most of
  it explaining a bug that no longer exists. The operative facts stay: the
  hook builds a summary, so it belongs only on one path and is omitted rather
  than blanked.
- `unwrap_math` cited the `_repr_latex_` defect by name after already stating
  what goes wrong.
- The module docstring's naming rationale is a decision record; it lives in
  the commit that made it and in the guide.
- `_pparts` restated the whole contract in prose written before
  `guides/formatting.md` existed. It keeps the name list -- that is what a
  downstream reader wants without leaving the module -- and points at the
  guide for the grammar and worked examples.

Kept deliberately: `PGroup`'s two bullets, which are what stop someone
"simplifying" the nesting into invalid LaTeX, and `_render_call`'s note that
`__pdoc__` is where reconstruction lives, without which the indirection looks
pointless.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Order-independence requires a flat keyword namespace: a bare token has to
identify its axis without help from position. The cost is that every axis
competes for one pool of words, and unxt has already claimed seventeen of the
most generic -- dim, name, type, full, text, array, values among them.

The failure that mattered was not "a name is taken" but whose error it was.
`coordinax` wanting `dim` for manifold dimensionality -- a different and
equally valid meaning -- was refused at *registration*. Two sibling packages
each wanting one word meant `import coordinax; import galax` raised in user
code, with neither library at fault and no fix available to either.

A keyword may now be written `axis:word`. Bare resolves while exactly one axis
claims it, which is every word today, so nothing changes for ordinary use.
When two claim one, the bare form is ambiguous and the error names both
qualified alternatives. Qualification is per-token: a collision costs one
prefix on one word, not a rewritten spec.

Registration no longer refuses a duplicate keyword. It still refuses a clash
with an *alias*, which is a whole spec and so has no qualified form to fall
back on.

A `:` naming no registered axis is not a qualifier -- it falls through to the
format spec like any other non-keyword, so a `:` fill character still works
(`f"{q::>6}"` -> ':::::3 m', verified).

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

An axis is offered to every type and quietly ignored by one with no concept of
it. That is deliberate -- it is what lets a composite forward axes it has never
heard of, so `f"{interval:name}"` reaches the nested quantities -- but it means
a spec can be accepted and do nothing. Two live examples:

- `f"{q:name}"` on `km / s`: a composite unit has no long name, so the axis
  falls back to the symbol.
- `f"{q:dims}"` on a Quantity: the alias expands to `call-dim`, which only
  unit systems honour. Identical output to `f"{q:call}"`.

Applicability cannot be declared per type -- a composite genuinely does not
honour `unit`, yet forwarding makes it work, and the answer depends on the
object *tree*, which is not known before rendering. So ask by experiment
instead: render again with the axis reset to its default and see whether the
output moves. That needs no cooperation from the type and sees through
composites for free. Measured against both warts above and the live cases
(`name`/`dim` on a simple unit, `mul`, `latex-mul`, `.2f`): no false positives.

Off by default, because each probe is a second render -- 1.7x on a one-axis
spec, 5x on `latex-mul-name`. `repr`/`str` are unaffected either way; they
reach `render` directly and never pass through `pspec`.

The flag is `WARN_INERT_AXES` on the engine rather than a trait in
`unxt.config`, so it survives extraction: a consuming library sets it for
itself instead of the engine reaching into any one library's configuration.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

`f"{q:latex}"` emitted `$[1.5,~2.5] \mathrm{m}$` -- a *literal* space, which
LaTeX discards in math mode. The default rendering therefore set the unit
flush against the value.

A regression from this PR: `bare` became the default separator (right for
`f"{q:.2f}"` staying astropy-shaped), and `bare` had no LaTeX spelling, so it
fell back to the plain-text `" "`.

The deeper cause is that `sep` substituted a *literal string* chosen by the
axis, bypassing the markup table entirely -- so no LaTeX override could ever
apply to it, and adding one had no effect. `sep` now names the **role** that
stands in for `mul`, which routes it through the same per-role lookup every
other fragment uses. Each markup then spells its own join: `" "` for text and
HTML, `\,` -- the thin space conventionally set between a quantity and its
unit -- for LaTeX.

`mul` keeps `\;` in LaTeX. `1.5 \times \mathrm{m}` is not how a quantity is
written, so there the axis chooses between two spacings rather than showing an
operator.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>